home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_groff.idb / usr / freeware / info / groff-5.z / groff-5
Text File  |  2002-04-08  |  51KB  |  1,668 lines
  1. This is groff, produced by makeinfo version 4.0 from groff.texinfo.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * Groff: (groff).  The GNU troff document formatting system.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This Info file documents GNU troff version 1.16.
  9.  
  10.    Published by the Free Software Foundation 59 Temple Place, Suite 330
  11. Boston, MA  02111-1307  USA
  12.  
  13.    Copyright (C) 1994-2000 Free Software Foundation, Inc.
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided that the
  21. entire resulting derived work is distributed under the terms of a
  22. permission notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that this permission notice may be stated in a
  27. translation approved by the Foundation.
  28.  
  29.    Permission is granted to copy and distribute modified versions of
  30. this manual under the conditions for verbatim copying, provided also
  31. that the section entitled "GNU General Public License" is included
  32. exactly as in the original, and provided that the entire resulting
  33. derived work is distributed under the terms of a permission notice
  34. identical to this one.
  35.  
  36.    Permission is granted to copy and distribute translations of this
  37. manual into another language, under the above conditions for modified
  38. versions, except that the section entitled "GNU General Public License"
  39. may be included in a translation approved by the Free Software
  40. Foundation instead of in the original English.
  41.  
  42. 
  43. File: groff,  Node: Writing Macros,  Next: Page Motions,  Prev: Conditionals and Loops,  Up: gtroff Reference
  44.  
  45. Writing Macros
  46. ==============
  47.  
  48.    A "macro" is a collection of text and embedded commands which can be
  49. invoked multiple times.  Use macros to define common operations.
  50.  
  51.  - Request: .de name [end]
  52.      Define a new macro named NAME.  `gtroff' copies subsequent lines
  53.      (starting with the next one) into an internal buffer until it
  54.      encounters the line `..' (two dots).  The optional second argument
  55.      to `de' changes this to a macro to `.END'.
  56.  
  57.      Note that no leading whitespace is allowed in the line containing
  58.      the ending token (either `..' or the macro `.END').
  59.  
  60.      Here a small example macro called `P' which causes a break and
  61.      inserts some vertical space.  It could be used to separate
  62.      paragraphs.
  63.  
  64.  
  65.           .de P
  66.           .  br
  67.           .  sp .8v
  68.           ..
  69.  
  70.  
  71.  - Request: .am xx
  72.      Works similarly to `de' except it appends onto the macro named XX.
  73.      So, to make the previously defined `P' macro actually do indented
  74.      instead of block paragraphs, add the necessary code to the
  75.      existing macro like this:
  76.  
  77.  
  78.           .am P
  79.           .ti +5n
  80.           ..
  81.  
  82.  
  83.  - Request: .als new old
  84.      Create an alias named NEW for the request, string, macro, or
  85.      diversion object named OLD.  The new name and the old name are
  86.      exactly equivalent (it is similar to a hard rather than a soft
  87.      link). If OLD is undefined, `gtroff' generates a warning of type
  88.      `mac' and ignores the request.
  89.  
  90.      The `de', `am', `di', `da', `ds', and `as' requests only create a
  91.      new object if the name of the macro, diversion or string diversion
  92.      is currently undefined or if it is defined to be a request;
  93.      normally they modify the value of an existing object.
  94.  
  95. * Menu:
  96.  
  97. * Copy-in Mode::
  98. * Parameters::
  99.  
  100. 
  101. File: groff,  Node: Copy-in Mode,  Next: Parameters,  Prev: Writing Macros,  Up: Writing Macros
  102.  
  103. Copy-in Mode
  104. ------------
  105.  
  106.    When `gtroff' reads in the text for a macro or diversion, it copies
  107. the text (including request lines, but excluding escapes) into an
  108. internal buffer.  Escapes are converted into an internal form, except
  109. for `\n', `\$', `\*', `\\' and `\<RET>' which are evaluated and
  110. inserted into the text where the escape was located.  This is known as
  111. "copy-in" mode or "copy" mode.
  112.  
  113.    What this means is that you can specify when these escapes are to be
  114. evaluated (either at copy-in time or at the time of use) by insulating
  115. the escapes with an extra backslash.  Compare this to the `\def' and
  116. `\edef' commands in TeX.
  117.  
  118.    The following example prints the numbers 20 and 10:
  119.  
  120.  
  121.      .nr x 20
  122.      .de y
  123.      .nr x 10
  124.      \&\nx
  125.      \&\\nx
  126.      ..
  127.      .y
  128.  
  129. 
  130. File: groff,  Node: Parameters,  Prev: Copy-in Mode,  Up: Writing Macros
  131.  
  132. Parameters
  133. ----------
  134.  
  135.    The arguments to a macro can be examined using a variety of escapes.
  136. The number of arguments is available in the `.$' number register.  Any
  137. individual argument can be retrieved with one of the following escapes:
  138.  
  139.  - Escape: \$n
  140.  - Escape: \$(NN
  141.  - Escape: \$[NNN]
  142.      The escapes `\$N', `\$(NN' and `\$[NNN]' retrieve the Nth, NNth or
  143.      NNNth argument.  As usual, the first form only accepts a single
  144.      number (larger than zero), the second a two-digit number (larger
  145.      or equal to 10), and the third any positive integer value (larger
  146.      than zero).  Macros can have an unlimited number of arguments.
  147.      Note that due to copy-in mode, use two backslashes on these in
  148.      actual use to prevent interpolation until the macro is actually
  149.      invoked.
  150.  
  151.  - Request: .shift [n]
  152.      Shifts the arguments 1 position, or as many positions as specified
  153.      by its argument.  After executing this request, argument I becomes
  154.      argument I-N; arguments 1 to N are no longer available.  Shifting
  155.      by negative amounts is currently undefined.
  156.  
  157.  - Escape: \$*
  158.  - Escape: \$@
  159.      In some cases it is convenient to use all of the arguments at once
  160.      (for example, to pass the arguments along to another macro).  The
  161.      `\$*' escape concatenates all the arguments separated by spaces.  A
  162.      similar escape is `\$@', which concatenates all the arguments with
  163.      each surrounded by double quotes, and separated by spaces.
  164.  
  165.  - Escape: \$0
  166.      The name used to invoke the current macro.  The `als' request can
  167.      make a macro have more than one name.
  168.  
  169.  
  170.           .de vl
  171.           .ie \\n(.$=1 .ds Vl Pre-Release Version
  172.           .el          .ds Vl Version \\$3, \\$4.
  173.           ..
  174.  
  175.      This would be called as
  176.  
  177.  
  178.           .vl $Id: groff.texinfo,v 1.77 2001/05/07 13:36:24 wlemb Exp $
  179.  
  180.  
  181.    *Note Request Arguments::.
  182.  
  183. 
  184. File: groff,  Node: Page Motions,  Next: Drawing Requests,  Prev: Writing Macros,  Up: gtroff Reference
  185.  
  186. Page Motions
  187. ============
  188.  
  189.  - Request: .sp [len]
  190.      Motions up and down the page can be done with the `sp' request.
  191.      However, this causes a break so that the actual effect is to move
  192.      to the left margin and then to the specified location.
  193.  
  194.  - Request: .mk [reg]
  195.  - Request: .rt reg
  196.      The request `mk' can be used to mark a location on a page, for
  197.      movement to later.  This request takes a register name as an
  198.      argument in which to store the current page location.  With no
  199.      argument it stores the location in an internal register.  The
  200.      results of this can be used later by the `rt' or the `sp' request.
  201.      The `rt' request returns _upwards_ to the location given in the
  202.      register name given as an argument; with no argument it returns to
  203.      the location marked with the `mk' request.
  204.  
  205.  
  206.    The following escapes give fine control of movements about the page.
  207.  
  208.  - Escape: \v'E'
  209.      The `\v'E'' escape enables arbitrary vertical motion from the
  210.      current location on the page.  The argument E specifies the
  211.      distance to move; positive is downwards and negative upwards.  The
  212.      default unit for this escape `v'.  Beware, however, that `gtroff'
  213.      continues text processing at the point where the motion ends, so
  214.      you should always balance motions to avoid interference with text
  215.      processing.
  216.  
  217.    There are some special case escapes for vertical motion.
  218.  
  219. `\r'
  220.      move upwards 1v.
  221.  
  222. `\u'
  223.      move upwards .5v.
  224.  
  225. `\d'
  226.      move down .5v.
  227.  
  228.  - Escape: \h'E'
  229.      The `\h'E'' escape provides horizontal motions.  The expression E
  230.      indicates how far to move: positive is rightwards and negative
  231.      leftwards.
  232.  
  233.    There are a number of special case escapes for horizontal motion:
  234.  
  235. `\<SP>'
  236.      An unbreakable and unpaddable (i.e. not expanded during filling)
  237.      space.  (Note: This is a backslash followed by a space.)
  238.  
  239. `\~'
  240.      An unbreakable space that stretches like a normal inter-word space
  241.      when a line is adjusted.
  242.  
  243. `\|'
  244.      A 1/6th em space.  Ignored for tty output devices (rounded to
  245.      zero).
  246.  
  247. `\^'
  248.      A 1/12th em space.  Ignored for tty output devices (rounded to
  249.      zero).
  250.  
  251. `\0'
  252.      A space the size of a digit.
  253.  
  254. `\&'
  255.      A zero width space.
  256.  
  257. `\)'
  258.      Like `\&' except that it behaves like a character declared with the
  259.      `cflags' request to be transparent for the purposes of end of
  260.      sentence recognition.
  261.  
  262.    The following string sets the TeX logo:
  263.  
  264.  
  265.      .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
  266.  
  267.  - Escape: \w'TEXT'
  268.      Used as `\w'TEXT'', returns the width of the specified TEXT in
  269.      basic units.  This allows horizontal movement based on the width
  270.      of some arbitrary text (e.g. given as an argument to a macro).
  271.  
  272.      Font changes may occur in TEXT which don't affect current settings.
  273.  
  274.      After use, `\w' sets several registers:
  275.  
  276.     `st'
  277.     `sb'
  278.           The highest and lowest point, respectively, in TEXT.
  279.  
  280.     `rst'
  281.     `rsb'
  282.           Like the `st' and `sb' registers, but takes account of the
  283.           heights and depths of characters.
  284.  
  285.     `ct'
  286.           Defines the kinds of characters occurring in TEXT:
  287.  
  288.          0
  289.                only short characters, no descenders or tall characters.
  290.  
  291.          1
  292.                at least one descender.
  293.  
  294.          2
  295.                at least one tall character.
  296.  
  297.          3
  298.                at least one each of a descender and a tall character.
  299.  
  300.     `ssc'
  301.           The amount of horizontal space (possibly negative) that
  302.           should be added to the last character before a subscript.
  303.  
  304.     `skw'
  305.           How far to right of the center of the last character in the
  306.           `\w' argument, the center of an accent from a roman font
  307.           should be placed over that character.
  308.  
  309.  - Escape: \k'X'
  310.      Stores the current horizontal position in register X.  Use this,
  311.      for example, to return to the beginning of a string for
  312.      highlighting or other decoration.
  313.  
  314.  - Register: \n[.k]
  315.      A read-only number register containing the current horizontal
  316.      output position.
  317.  
  318. 
  319. File: groff,  Node: Drawing Requests,  Next: Traps,  Prev: Page Motions,  Up: gtroff Reference
  320.  
  321. Drawing Requests
  322. ================
  323.  
  324.    `gtroff' provides a number of ways to draw lines and other figures
  325. on the page.  Used in combination with the page motion commands (see
  326. *Note Page Motions::, for more info), a wide variety of figures can be
  327. drawn.  However, for complex drawings these operations can be quite
  328. cumbersome, and it may be wise to use graphic preprocessors like `gpic'
  329. or `ggrn'.  *Note gpic::, and *Note ggrn::, for more information.
  330.  
  331.    All drawing is done via escapes.
  332.  
  333.  - Escape: \l'L C'
  334.      Draws a line rightwards from the current location.  The full
  335.      syntax for this escape is:
  336.  
  337.  
  338.           \l'LC'
  339.  
  340.      where L is the length of the line to be drawn, starting at the
  341.      current location; positive numbers draw to the right, and negative
  342.      numbers draw towards the left.  This can also be specified
  343.      absolutely (i.e. with a leading `|') which draws back to the
  344.      beginning of the line.
  345.  
  346.      The optional second parameter C is a character to draw the line
  347.      with.  If this second argument is not specified, `gtroff' uses the
  348.      underscore character.
  349.  
  350.      To separate the two arguments (to prevent `gtroff' from
  351.      interpreting a drawing character as a scaling indicator) use `\&'.
  352.  
  353.      Here a small useful example:
  354.  
  355.  
  356.           .de box
  357.           \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
  358.           ..
  359.  
  360.      Note that this works by outputting a box rule (a vertical line),
  361.      then the text given as an argument and then another box rule.
  362.      Then the line drawing escapes both draw from the current location
  363.      to the beginning of the _input_ line.
  364.  
  365.  - Escape: \L'L C'
  366.      Draws vertical lines.  Its parameters are similar to the `\l'
  367.      escape.  The movement is downwards for positive values, and
  368.      upwards for negative values.  The default character is the box
  369.      rule character.  As with the vertical motion escapes, text
  370.      processing blindly continues where the line ends.
  371.  
  372.  
  373.  - Escape: \D'COMMAND ARG ...'
  374.      The `\D' escape provides a variety of drawing functions.  While
  375.      the previous escapes work on a character device, these escapes do
  376.      not.
  377.  
  378.     `\D'l DX DY''
  379.           Draw a line from the current location to the relative point
  380.           specified by (DX,DY).
  381.  
  382.     `\D'c D''
  383.           Draw a circle with a diameter of D with the leftmost point at
  384.           the current position.
  385.  
  386.     `\D'C D''
  387.           Draw a solid circle with the same parameters as an outlined
  388.           circle.
  389.  
  390.     `\D'e DX DY''
  391.           Draw an ellipse with a horizontal diameter of DX and a
  392.           vertical diameter of DY with the leftmost point at the
  393.           current position.
  394.  
  395.     `\D'E DX DY''
  396.           Draw a solid ellipse with the same parameters as an outlined
  397.           ellipse.
  398.  
  399.     `\D'a DX1 DY1 DX2 DY2''
  400.           Draw an arc clockwise from the current location through the
  401.           two specified locations (DX1,DY1) and (DX2,DY2).
  402.  
  403.     `\D'~ DX1 DY1 DX2 DY2 ...''
  404.           Draw a spline from the current location to (DX1,DY1) and then
  405.           to (DX2,DY2), and so on.
  406.  
  407.     `\D'f N''
  408.           Set the shade of gray to be used for filling solid objects
  409.           to N; N must be an integer between 0 and 1000, where 0
  410.           corresponds solid white and 1000 to solid black, and values
  411.           in between correspond to intermediate shades of gray.  This
  412.           applies only to solid circles, solid ellipses and solid
  413.           polygons.  By default, a level of 1000 is used.
  414.  
  415.     `\D'p DX1 DY1 DX2 DY2 ...''
  416.           Draw a polygon from the current location to (DX1,DY1) and
  417.           then to (DX2,DY2) and so on.  When the specified data points
  418.           are exhausted, a line is drawn back to the starting point.
  419.  
  420.     `\D'P DX1 DY1 DX2 DY2 ...''
  421.           Draw a solid polygon with the same parameters as an outlined
  422.           polygon.
  423.  
  424.     `\D't N''
  425.           Set the current line thickness to N machine units.  A value of
  426.           zero selects the smallest available line thickness.  A
  427.           negative value makes the line thickness proportional to the
  428.           current point size (this is the default behaviour of
  429.           `ditroff').
  430.  
  431.  - Escape: \b'STRING'
  432.      "Piles" a sequence of characters vertically, and centers it
  433.      vertically on the current line.  Use it to build large brackets
  434.      and braces.
  435.  
  436.  
  437.           \b'\(lt\(bv\(lk\(bv\(lb'
  438.  
  439.  
  440.    *Note Drawing Functions::.
  441.  
  442. 
  443. File: groff,  Node: Traps,  Next: Diversions,  Prev: Drawing Requests,  Up: gtroff Reference
  444.  
  445. Traps
  446. =====
  447.  
  448.    "Traps" are locations, which, when reached, call a specified macro.
  449. These traps can occur at a given location on the page, at a given
  450. location in the current diversion, after a certain number of input
  451. lines or at the end of input.
  452.  
  453. * Menu:
  454.  
  455. * Page Location Traps::
  456. * Diversion Traps::
  457. * Input Line Traps::
  458. * End-of-input Traps::
  459.  
  460. 
  461. File: groff,  Node: Page Location Traps,  Next: Diversion Traps,  Prev: Traps,  Up: Traps
  462.  
  463. Page Location Traps
  464. -------------------
  465.  
  466.    "Page location traps" perform an action when `gtroff' reaches a
  467. certain vertical location on the page.  Page location traps have a
  468. variety of purposes, including:
  469.  
  470.    * setting headers and footers
  471.  
  472.    * setting body text in multiple columns
  473.  
  474.    * setting footnotes
  475.  
  476.  - Request: .vpt flag
  477.  - Register: \n[.vpt]
  478.      Enables vertical position traps if FLAG is non-zero, or disables
  479.      them otherwise.  Vertical position traps are traps set by the `wh'
  480.      or `dt' requests.  Traps set by the `it' request are not vertical
  481.      position traps.  The parameter that controls whether vertical
  482.      position traps are enabled is global.  Initially vertical position
  483.      traps are enabled.  The current setting of this is available in the
  484.      `.vpt' read-only number register.
  485.  
  486.  - Request: .wh dist macro
  487.      Sets a page location trap.  Positive values for DIST set the trap
  488.      relative to the top of the page; negative values set the trap
  489.      relative to the bottom of the page.
  490.  
  491.      MACRO is the name of the macro to execute when the trap is sprung.
  492.  
  493.      The following is a simple example of how many macro packages set
  494.      headers and footers.
  495.  
  496.  
  497.           .de hd                \" Page header
  498.           'sp .5i
  499.           .tl 'Title''date'
  500.           'sp .3i
  501.           ..
  502.           .de fo                \" Page footer
  503.           'sp 1v
  504.           .tl ''%''
  505.           'bp
  506.           ..
  507.           .wh 0   hd            \" trap at top of the page
  508.           .wh -1i fo            \" trap one inch from bottom
  509.  
  510.  
  511.  - Register: \n[.t]
  512.      A read-only number register holding the distance to the next trap.
  513.  
  514.  - Request: .ch dist macro
  515.      Changes the location of a trap.  The first argument is the name of
  516.      the macro to be invoked at the trap, and the second argument is
  517.      the new location for the trap (note that the parameters are
  518.      specified the opposite of the `.wh' request).  This is useful for
  519.      building up footnotes in a diversion to allow more space at the
  520.      bottom of the page for them.
  521.  
  522.  
  523.  - Register: \n[.ne]
  524.      The read-only number register `.ne' contains the amount of space
  525.      that was needed in the last `ne' request that caused a trap to be
  526.      sprung.  Useful in conjunction with the `.trunc' register.  *Note
  527.      Page Control::, for more information.
  528.  
  529.  - Register: \n[.trunc]
  530.      A read-only register containing the amount of vertical space
  531.      truncated by the most recently sprung vertical position trap, or,
  532.      if the trap was sprung by an `ne' request, minus the amount of
  533.      vertical motion produced by the `ne' request.  In other words, at
  534.      the point a trap is sprung, it represents the difference of what
  535.      the vertical position would have been but for the trap, and what
  536.      the vertical position actually is.
  537.  
  538. 
  539. File: groff,  Node: Diversion Traps,  Next: Input Line Traps,  Prev: Page Location Traps,  Up: Traps
  540.  
  541. Diversion Traps
  542. ---------------
  543.  
  544.  - Request: .dt dist macro
  545.      Sets a trap _within_ a diversion.  DIST is the first argument is
  546.      the location of the trap (identical to the `.wh' request) and
  547.      MACRO is the name of the macro to be invoked.  The number register
  548.      `.t' still works within diversions.  *Note Diversions::, for more
  549.      information.
  550.  
  551. 
  552. File: groff,  Node: Input Line Traps,  Next: End-of-input Traps,  Prev: Diversion Traps,  Up: Traps
  553.  
  554. Input Line Traps
  555. ----------------
  556.  
  557.  - Request: .it n macro
  558.      Sets an input line trap.  N is the number of lines of input which
  559.      may be read before "springing" the trap, MACRO is the macro to be
  560.      invoked.  Request lines are not counted as input lines.
  561.  
  562.      For example, one possible use is to have a macro which prints the
  563.      next N lines in a bold font.
  564.  
  565.  
  566.           .de B
  567.           .it \\$1 B-end
  568.           .ft B
  569.           ..
  570.           .de B-end
  571.           .ft R
  572.           ..
  573.  
  574.  
  575. 
  576. File: groff,  Node: End-of-input Traps,  Prev: Input Line Traps,  Up: Traps
  577.  
  578. End-of-input Traps
  579. ------------------
  580.  
  581.  - Request: .em macro
  582.      Sets a trap at the end of input.  The MACRO specified is executed
  583.      after the last line of the input file has been processed.
  584.  
  585.      For example, if the document had to have a section at the bottom
  586.      of the last page for someone to approve it, the `em' request could
  587.      be used.
  588.  
  589.  
  590.           .de approval
  591.           .ne 5v
  592.           .sp |(\\n(.t-6v)
  593.           .in +4i
  594.           .lc _
  595.           .br
  596.           Approved:\t\a
  597.           .sp
  598.           Date:\t\t\a
  599.           ..
  600.           .em approval
  601.  
  602.  
  603. 
  604. File: groff,  Node: Diversions,  Next: Environments,  Prev: Traps,  Up: gtroff Reference
  605.  
  606. Diversions
  607. ==========
  608.  
  609.    In `gtroff' it is possible to "divert" text into a named storage
  610. area.  Due to the similarity to defining macros it is sometimes said to
  611. be stored in a macro.  This is used for saving text for output at a
  612. later time, which is useful for keeping blocks of text on the same
  613. page, footnotes, tables of contents and indices.
  614.  
  615.  - Request: .di macro
  616.  - Request: .da macro
  617.      Begins a diversion.  Like the `de' request, it takes an argument
  618.      of a macro name to divert subsequent text into.  The `da' macro
  619.      appends to an existing diversion.
  620.  
  621.      `di' or `da' without an argument ends the diversion.
  622.  
  623.  
  624.  - Register: \n[.z]
  625.  - Register: \n[.d]
  626.      Diversions may be nested.  The read-only number register `.z'
  627.      contains the name of the current diversion (this is a string-valued
  628.      register).  The read-only number register `.d' contains the current
  629.      vertical place in the diversion.  If not in a diversion it is the
  630.      same as the register `nl'.
  631.  
  632.  - Register: \n[.h]
  633.      The "high-water mark" on the current page.  It corresponds to the
  634.      text baseline of the lowest line on the page.  This is a read-only
  635.      register.
  636.  
  637.  - Register: \n[dn]
  638.  - Register: \n[dl]
  639.      After completing a diversion, the read-write number registers `dn'
  640.      and `dl' contain the vertical and horizontal size of the diversion.
  641.  
  642.           .\" Center text both horizontally & vertically
  643.           .de (c
  644.           .br
  645.           .nf
  646.           .di @c
  647.           ..
  648.           .de )c
  649.           .br
  650.           .di
  651.           .nr @s (((\\n(.tu-\\n(dnu)/2u)-1v)
  652.           .sp \\n(@su
  653.           .ce 1000
  654.           .nf
  655.           ..br
  656.           .ce 0
  657.           .sp \\n(@su
  658.           .br
  659.           .fi
  660.           .rr @s
  661.           ..
  662.  
  663.  - Escape: \!
  664.  - Escape: \?ANYTHING\?
  665.      Prevents requests, macros and escapes from being interpreted when
  666.      read into a diversion.  This takes the given text and
  667.      "transparently" embeds it into the diversion.  This is useful for
  668.      macros which shouldn't be invoked until the diverted text is
  669.      actually output.
  670.  
  671.      The `\!' escape transparently embeds text up to and including the
  672.      end of the line.  The `\?' escape transparently embeds text until
  673.      the next occurrence of the `\?' escape.  For example:
  674.  
  675.  
  676.           \?ANYTHING\?
  677.  
  678.      ANYTHING may not contain newlines; use `\!'  to embed newlines in
  679.      a diversion.  The escape sequence `\?' is also recognized in copy
  680.      mode and turned into a single internal code; it is this code that
  681.      terminates anything.  Thus the following example prints 4.
  682.  
  683.  
  684.           .nr x 1
  685.           .nf
  686.           .di d
  687.           \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
  688.           .di
  689.           .nr x 2
  690.           .di e
  691.           .d
  692.           .di
  693.           .nr x 3
  694.           .di f
  695.           .e
  696.           .di
  697.           .nr x 4
  698.           .f
  699.  
  700.  
  701.  - Request: .asciify div
  702.      "Unformats" the diversion specified by DIV in such a way that
  703.      ASCII and space characters that were formatted and diverted are
  704.      treated like ordinary input characters when the diversion is
  705.      reread.  It can be also used for gross hacks; for example, the
  706.      following sets register `n' to 1.
  707.  
  708.  
  709.           .tr @.
  710.           .di x
  711.           @nr n 1
  712.           .br
  713.           .di
  714.           .tr @@
  715.           .asciify x
  716.           .x
  717.  
  718.      *Note Copy-in Mode::.
  719.  
  720. 
  721. File: groff,  Node: Environments,  Next: Suppressing output,  Prev: Diversions,  Up: gtroff Reference
  722.  
  723. Environments
  724. ============
  725.  
  726.    It happens frequently that some text should be printed in a certain
  727. format regardless of what may be in effect at the time, for example, in
  728. a trap invoked macro to print headers and footers.  To solve this
  729. `gtroff' processes text in "environments".  An environment contains
  730. most of the parameters that control text processing.  It is possible to
  731. switch amongst these environments; by default `gtroff' processes text
  732. in environment 0.  The following is the information kept in an
  733. environment.
  734.  
  735.    * font parameters (size, family, style, character height and slant,
  736.      space and sentence space size)
  737.  
  738.    * page parameters (line length, title length, vertical spacing, line
  739.      spacing, indentation, line numbering, hyphenation data)
  740.  
  741.    * fill and adjust mode
  742.  
  743.    * tab stops, tab and leader characters, escape character, no-break
  744.      and hyphen indicators, margin character data
  745.  
  746.    * partially collected lines
  747.  
  748.    These environments may be given arbitrary names (see *Note
  749. Identifiers::, for more info).  Old versions of `troff' only had
  750. environments named `0', `1' and `2'.
  751.  
  752.  - Request: .ev env
  753.  - Register: \n[.ev]
  754.      Switches to another environment.  The argument ENV is the name of
  755.      the environment to switch to.  With no argument, `gtroff' switches
  756.      back to the previous environment.  There is no limit on the number
  757.      of named environments; they are created the first time that they
  758.      are referenced.  The `.ev' read-only register contains the name or
  759.      number of the current environment.  This is a string-valued
  760.      register.
  761.  
  762.      Note that a call to `ev' (with argument) pushes the previously
  763.      active environment onto a stack.  If, say, environments `foo',
  764.      `bar', and `zap' are called (in that order), the first `ev'
  765.      request without parameter switches back to environment `bar'
  766.      (which is popped off the stack), and a second call switches back
  767.      to environment `foo'.
  768.  
  769.      Here is an example:
  770.  
  771.  
  772.           .ev footnote-env
  773.           .fam N
  774.           .ps 6
  775.           .vs 8
  776.           .ll -.5i
  777.           .ev
  778.           
  779.           ...
  780.           
  781.           .ev footnote-env
  782.           \(dg Note the large, friendly letters.
  783.           .ev
  784.  
  785.  
  786.  - Request: .evc env
  787.      Copies the environment ENV into the current environment.
  788.  
  789. 
  790. File: groff,  Node: Suppressing output,  Next: I/O,  Prev: Environments,  Up: gtroff Reference
  791.  
  792. Suppressing output
  793. ==================
  794.  
  795.  - Escape: \ONUM
  796.      Disables or enables output depending on the value of NUM:
  797.  
  798.     `\O0'
  799.           Disable any ditroff glyphs from being emitted to the device
  800.           driver.
  801.  
  802.     `\O1'
  803.           Enable output of glyphs.
  804.  
  805.      `\O0' and `\O1' also reset the four registers `opminx', `opminy',
  806.      `opmaxx', and `opmaxy' to -1.  *Note Register Index::.  These four
  807.      registers mark the top left and bottom right hand corners of a box
  808.      which encompasses all written glyphs.
  809.  
  810.      The following two forms of `\O' are specific to `grohtml'.
  811.  
  812.     `\O2'
  813.           Disable any ditroff glyphs from being emitted to the device
  814.           driver.  Also write out to `stderr' the page number and four
  815.           registers encompassing the glyphs previously written since
  816.           the last call to `\O'.
  817.  
  818.     `\O3'
  819.           Enable output of glyphs (the default).  Also write out to
  820.           `stderr' the page number and four registers encompassing the
  821.           glyphs previously written since the last call to `\O'.
  822.  
  823. 
  824. File: groff,  Node: I/O,  Next: Postprocessor Access,  Prev: Suppressing output,  Up: gtroff Reference
  825.  
  826. I/O
  827. ===
  828.  
  829.    `gtroff' has several requests for including files:
  830.  
  831.  - Request: .so file
  832.      Reads in the specified FILE and includes it in place of the `so'
  833.      request.  This is quite useful for large documents, e.g. keeping
  834.      each chapter in a separate file.  *Note gsoelim::, for more
  835.      information.
  836.  
  837.  - Request: .mso file
  838.      Identical to the `so' request except that `gtroff' searches for
  839.      the specified FILE in the same directories as macro files for the
  840.      the `-m' command line option.  If the file name to be included has
  841.      the form `NAME.tmac' and it isn't found, `mso' tries to include
  842.      `tmac.NAME' and vice versa.
  843.  
  844.  - Request: .cf file
  845.  - Request: .trf file
  846.      Transparently outputs the contents of FILE.  Each line is output
  847.      as it were preceded by `\!'; however, the lines are not subject to
  848.      copy mode interpretation.  If the file does not end with a
  849.      newline, then a newline is added.  For example, to define a
  850.      macro `x' containing the contents of file `f', use
  851.  
  852.  
  853.           .di x
  854.           .trf f
  855.           .di
  856.  
  857.      The request `.cf FILENAME', when used in a diversion, embeds an
  858.      object in the diversion which, when reread, causes the contents of
  859.      FILENAME to be transparently copied through to the output.
  860.  
  861.      In UNIX `troff', the contents of FILENAME is immediately copied
  862.      through to the output regardless of whether there is a current
  863.      diversion; this behaviour is so anomalous that it must be
  864.      considered a bug.  This request causes a line break.
  865.  
  866.      With `trf', unlike `cf', the file cannot contain characters such
  867.      as NUL that are not valid `gtroff' input characters (*note
  868.      Identifiers::).  This request causes a line break.
  869.  
  870.  - Request: .nx
  871.      Forces `gtroff' to continue processing of the file specified as an
  872.      argument.
  873.  
  874.  - Request: .rd
  875.      The `rd' request reads from standard input, and includes what is
  876.      read as though it were part of the input file.  Text is read until
  877.      a blank line is encountered.
  878.  
  879.    Using the `nx' and `rd' requests, it is easy to set up form letters.
  880. The form letter template is constructed like this:
  881.  
  882.  
  883.      .ce
  884.      \*(td
  885.      .sp 2
  886.      .nf
  887.      .rd
  888.      .sp
  889.      .rd
  890.      .fi
  891.      Body of letter.
  892.      .bp
  893.      .nx repeat.let
  894.  
  895. When this is run, the following file should be redirected in.  Note that
  896. requests included in this file are executed as though they were part of
  897. the form letter.  The last block of input is the `ex' requests which
  898. tells groff to stop processing.  If this was not there, groff would not
  899. know when to stop.
  900.  
  901.  
  902.      Trent A. Fisher
  903.      708 NW 19th Av., #202
  904.      Portland, OR  97209
  905.      
  906.      Dear Trent,
  907.      
  908.      Len Adollar
  909.      4315 Sierra Vista
  910.      San Diego, CA  92103
  911.      
  912.      Dear Mr. Adollar,
  913.      
  914.      .ex
  915.  
  916.  - Request: .pi pipe
  917.      Pipes the output of `gtroff' to the shell command(s) specified by
  918.      PIPE.  This request must occur before `gtroff' has a chance to
  919.      print anything.
  920.  
  921.  - Request: .sy cmds
  922.  - Register: \n[systat]
  923.      In "unsafe" mode, executes the shell command(s) specified by CMDS.
  924.      The output is not saved anyplace, so it is up to the user to do
  925.      so.
  926.  
  927.      For example, the following example introduces the current time
  928.      into a document:
  929.  
  930.  
  931.           .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
  932.                    (localtime(time))[2,1,0]' > /tmp/x\n[$$]
  933.           .so /tmp/x\n[$$]
  934.           .sy rm /tmp/x\n[$$]
  935.           \nH:\nM:\nS
  936.  
  937.      Note that this works by having the `perl' script (run by `sy')
  938.      print out the `nr' requests which set the number registers `H',
  939.      `M' and `S', and then reads those commands in with the `so'
  940.      request.
  941.  
  942.      The `systat' read-write number register contains the return value
  943.      of the `system()' function executed by the last `sy' request.
  944.  
  945.  - Request: .open stream file
  946.  - Request: .opena stream file
  947.      Opens the specified FILE for writing and associates the specified
  948.      STREAM with it.
  949.  
  950.      The `opena' is like `open', but if the file exists, append to it
  951.      instead of truncating it.
  952.  
  953.  - Request: .write stream data
  954.      Writes to the file associated with the specified STREAM.  The
  955.      stream must previously have been the subject of an open request.
  956.      The remainder of the line is interpreted as the `ds' request reads
  957.      its second argument: A leading `"' is stripped, and it is read in
  958.      copy-in mode.
  959.  
  960.  - Request: .close stream
  961.      Closes the specified STREAM; the stream is no longer an acceptable
  962.      argument to the `write' request.
  963.  
  964.  
  965.  - Escape: \V'XXX'
  966.      Interpolates the contents of the specified environment variable,
  967.      as returned by the function `getenv'.  Specify the argument to
  968.      `\V' as an identifier, i.e.  `\VX', `\V(XX' or `\V[XXX]'.  `\V' is
  969.      interpreted in copy-in mode.
  970.  
  971. 
  972. File: groff,  Node: Postprocessor Access,  Next: Miscellaneous,  Prev: I/O,  Up: gtroff Reference
  973.  
  974. Postprocessor Access
  975. ====================
  976.  
  977.    There are two escapes which give information directly to the
  978. postprocessor.  This is particularly useful for embedding POSTSCRIPT
  979. into the final document.
  980.  
  981.  - Escape: \X'XXX'
  982.      Embeds its argument into the `gtroff' output preceded with `x X'.
  983.  
  984.  - Escape: \Y'XXX'
  985.      The `\Y' escape is called with an identifier (i.e.  `\YX', `\Y(XX'
  986.      or `\Y[XXX]').  This is approximately equivalent to `\X'\*[XXX]''.
  987.      However, the contents of the string or macro XXX are not
  988.      interpreted; also it is permitted for XXX to have been defined as
  989.      a macro and thus contain newlines (it is not permitted for the
  990.      argument to `\X' to contain newlines).  The inclusion of newlines
  991.      requires an extension to the UNIX `troff' output format, and
  992.      confuses drivers that do not know about this extension.
  993.  
  994.    *Note Output Devices::.
  995.  
  996. 
  997. File: groff,  Node: Miscellaneous,  Next: Gtroff Internals,  Prev: Postprocessor Access,  Up: gtroff Reference
  998.  
  999. Miscellaneous
  1000. =============
  1001.  
  1002.    This section documents parts of `gtroff' which cannot (yet) be
  1003. categorized elsewhere in this manual.
  1004.  
  1005.  - Request: .nm start inc space indent
  1006.      Prints line numbers in the left margin.  START is the line number
  1007.      of the _next_ output line; this defaults to 1.  INC indicates on
  1008.      which lines numbers are printed, i.e. 5 means put line numbers on
  1009.      every 5 lines; this defaults to 1.  SPACE is the space to be left
  1010.      between the number and the text; this defaults to 1.  The fourth
  1011.      argument is the indentation of the line numbers.  Without
  1012.      arguments, line numbers are turned off.
  1013.  
  1014.  - Request: .nn [skip]
  1015.      Temporarily turns off line numbering.  The argument is the number
  1016.      of lines not to be numbered; this defaults to 1.
  1017.  
  1018.  
  1019.  - Request: .mc char dist
  1020.      Prints margin characters to the right of the text.  The first
  1021.      argument is the character to be printed, and the second argument
  1022.      is the distance away from the main body text.  With no arguments
  1023.      the margin characters are turned off.  If this occurs before a
  1024.      break, no margin character is printed.
  1025.  
  1026.      This is quite useful for indicating text that has changed, and, in
  1027.      fact, there are programs available for doing this (they are called
  1028.      `nrchbar' and `changebar' and can be found in any
  1029.      `comp.sources.unix' archive.
  1030.  
  1031.  
  1032.  - Request: .lf line filename
  1033.      A debugging aid for documents which are split into many files,
  1034.      then put together with `soelim' and other preprocessors.  The
  1035.      second argument is the name of the file and the first argument is
  1036.      the input line number in that file.  This way `gtroff' can produce
  1037.      error messages which are intelligible to the user.
  1038.  
  1039.  
  1040. 
  1041. File: groff,  Node: Gtroff Internals,  Next: Debugging,  Prev: Miscellaneous,  Up: gtroff Reference
  1042.  
  1043. `gtroff' Internals
  1044. ==================
  1045.  
  1046.    `gtroff' processes input in three steps.  One or more input
  1047. characters are converted to an "input token".  Then, one or more input
  1048. tokens are converted to an "output node".  Finally, output nodes are
  1049. converted to the intermediate output language understood by all output
  1050. devices.
  1051.  
  1052.    For example, the input string `fi\[:u]' is converted in a character
  1053. token `f', a character token `i', and a special token `:u'
  1054. (representing u umlaut).  Later on, the character tokens `f' and `i'
  1055. are merged to a single output node representing the ligature glyph
  1056. `fi'; the same happens with `:u'.  All output glyph nodes are
  1057. `processed' which means that they are invariably associated with a
  1058. given font, font size, advance width, etc.  During the formatting
  1059. process, `gtroff' itself adds various nodes to control the data flow.
  1060.  
  1061.    Macros, diversions, and strings collect elements in two chained
  1062. lists: a list of input tokens which have been passed unprocessed, and a
  1063. list of output nodes.  Consider the following the diversion.
  1064.  
  1065.  
  1066.      .di xxx
  1067.      a
  1068.      \!b
  1069.      c
  1070.      .br
  1071.      .di
  1072.  
  1073. It contains these elements.
  1074.  
  1075. node list            token list   element number
  1076. line start node      --           1
  1077. glyph node `a'       --           2
  1078. word space node      --           3
  1079. --                   `b'          4
  1080. --                   `\n'         5
  1081. glyph node `c'       --           6
  1082. vertical size node   --           7
  1083. vertical size node   --           8
  1084. --                   `\n'         9
  1085.  
  1086. Elements 1, 7, and 8 are inserted by `gtroff'; the latter two (which
  1087. are always present) specify the vertical extent of the last line,
  1088. possibly modified by `\v'.  The `br' request finishes the current
  1089. partial line, inserting a newline input token which is subsequently
  1090. converted to a space when the diversion is reread.  Note that the word
  1091. space node has a fixed width which isn't stretchable anymore.  To
  1092. convert horizontal space nodes back to input tokens, use the `unformat'
  1093. request.
  1094.  
  1095.    Macros only contain elements in the token list (and the node list is
  1096. empty); diversions and strings can contain elements in both lists.
  1097.  
  1098. 
  1099. File: groff,  Node: Debugging,  Next: Implementation Differences,  Prev: Gtroff Internals,  Up: gtroff Reference
  1100.  
  1101. Debugging
  1102. =========
  1103.  
  1104.    `gtroff' is not easy to debug, but there are some useful features
  1105. and strategies for debugging.
  1106.  
  1107.  - Request: .tm string
  1108.      Sends the STRING to the standard error stream; this is very useful
  1109.      for printing debugging output among other things.
  1110.  
  1111.  - Request: .ab [string]
  1112.      Similar to the `tm' request, except that it causes `gtroff' to
  1113.      stop processing.  With no argument it prints `User Abort'.
  1114.  
  1115.  - Request: .ex
  1116.      The `ex' request also causes `gtroff' to stop processing if
  1117.      encountered at the topmost level; see also *Note I/O::.
  1118.  
  1119.    When doing something involved it is useful to leave the debugging
  1120. statements in the code and have them turned on by a command line flag.
  1121.  
  1122.  
  1123.      .if \n(DB .tm debugging output
  1124.  
  1125. To activate these statements say
  1126.  
  1127.  
  1128.      groff -rDB=1 file
  1129.  
  1130.    If it is known in advance that there will be many errors and no
  1131. useful output, `gtroff' can be forced to suppress formatted output with
  1132. the `-z' flag.
  1133.  
  1134.  - Request: .pm
  1135.      The `pm' request prints out the entire symbol table on `stderr'.
  1136.  
  1137.  - Request: .pnr
  1138.      Prints the names and contents of all currently defined number
  1139.      registers on `stderr'.
  1140.  
  1141.  - Request: .ptr
  1142.      Prints the names and positions of all traps (not including input
  1143.      line traps and diversion traps) on `stderr'.  Empty slots in the
  1144.      page trap list are printed as well, because they can affect the
  1145.      priority of subsequently planted traps.
  1146.  
  1147.  - Request: .fl
  1148.      Instructs `gtroff' to flush its output immediately.  The intent is
  1149.      for interactive use.  `gtroff'; there is little other use for it.
  1150.      This request causes a line break.
  1151.  
  1152.  - Request: .backtrace
  1153.      The `backtrace' request prints a backtrace of the input stack to
  1154.      the standard error stream.
  1155.  
  1156.    `gtroff' has command line options for printing out more warnings
  1157. (`-w') and for printing backtraces (`-b') when a warning or an error
  1158. occurs.  The most verbose level of warnings is `-ww'.
  1159.  
  1160.  - Request: .warn [flags]
  1161.  - Register: \n[.warn]
  1162.      Controls the level of warnings checked for.  The FLAGS are the sum
  1163.      of the numbers associated with each warning that is to be enabled;
  1164.      all other warnings are disabled.  The number associated with each
  1165.      warning is listed below.  For example, `.warn 0' disables all
  1166.      warnings, and `.warn 1' disables all warnings except that about
  1167.      missing characters.  If an argument is not given, all warnings are
  1168.      enabled.
  1169.  
  1170.      The read-only number register `.warn' contains the current warning
  1171.      level.
  1172.  
  1173. * Menu:
  1174.  
  1175. * Warnings::
  1176.  
  1177. 
  1178. File: groff,  Node: Warnings,  Prev: Debugging,  Up: Debugging
  1179.  
  1180. Warnings
  1181. --------
  1182.  
  1183.    The warnings that can be given to `gtroff' are divided into the
  1184. following categories.  The name associated with each warning is used by
  1185. the `-w' and `-W' options; the number is used by the `warn' request and
  1186. by the `.warn' register.
  1187.  
  1188. `char'
  1189. `1'
  1190.      Non-existent characters.  This is enabled by default.
  1191.  
  1192. `number'
  1193. `2'
  1194.      Invalid numeric expressions.  This is enabled by default.  *Note
  1195.      Expressions::.
  1196.  
  1197. `break'
  1198. `4'
  1199.      In fill mode, lines which could not be broken so that their length
  1200.      was less than the line length.  This is enabled by default.
  1201.  
  1202. `delim'
  1203. `8'
  1204.      Missing or mismatched closing delimiters.
  1205.  
  1206. `el'
  1207. `16'
  1208.      Use of the `el' request with no matching `ie' request.  *Note
  1209.      if-else::.
  1210.  
  1211. `scale'
  1212. `32'
  1213.      Meaningless scaling indicators.
  1214.  
  1215. `range'
  1216. `64'
  1217.      Out of range arguments.
  1218.  
  1219. `syntax'
  1220. `128'
  1221.      Dubious syntax in numeric expressions.
  1222.  
  1223. `di'
  1224. `256'
  1225.      Use of `di' or `da' without an argument when there is no current
  1226.      diversion.
  1227.  
  1228. `mac'
  1229. `512'
  1230.      Use of undefined strings, macros and diversions.  When an undefined
  1231.      string, macro or diversion is used, that string is automatically
  1232.      defined as empty.  So, in most cases, at most one warning is given
  1233.      for each name.
  1234.  
  1235. `reg'
  1236. `1024'
  1237.      Use of undefined number registers.  When an undefined number
  1238.      register is used, that register is automatically defined to have a
  1239.      value of 0.  A definition is automatically made with a value of 0.
  1240.      So, in most cases, at most one warning is given for use of a
  1241.      particular name.
  1242.  
  1243. `tab'
  1244. `2048'
  1245.      Use of a tab character where a number was expected.
  1246.  
  1247. `right-brace'
  1248. `4096'
  1249.      Use of `\}' where a number was expected.
  1250.  
  1251. `missing'
  1252. `8192'
  1253.      Requests that are missing non-optional arguments.
  1254.  
  1255. `input'
  1256. `16384'
  1257.      Illegal input characters.
  1258.  
  1259. `escape'
  1260. `32768'
  1261.      Unrecognized escape sequences.  When an unrecognized escape
  1262.      sequence is encountered, the escape character is ignored.
  1263.  
  1264. `space'
  1265. `65536'
  1266.      Missing space between a request or macro and its argument.  This
  1267.      warning is given when an undefined name longer than two characters
  1268.      is encountered, and the first two characters of the name make a
  1269.      defined name.  The request or macro is not invoked.  When this
  1270.      warning is given, no macro is automatically defined.  This is
  1271.      enabled by default.  This warning never occurs in compatibility
  1272.      mode.
  1273.  
  1274. `font'
  1275. `131072'
  1276.      Non-existent fonts.  This is enabled by default.
  1277.  
  1278. `all'
  1279.      All warnings except `di', `mac' and `reg'.  It is intended that
  1280.      this covers all warnings that are useful with traditional macro
  1281.      packages.
  1282.  
  1283. `w'
  1284.      All warnings.
  1285.  
  1286. 
  1287. File: groff,  Node: Implementation Differences,  Next: Summary,  Prev: Debugging,  Up: gtroff Reference
  1288.  
  1289. Implementation Differences
  1290. ==========================
  1291.  
  1292.    GNU `troff' has a number of features which cause incompatibilities
  1293. with documents written with old versions of `troff'.
  1294.  
  1295.    Long names cause some incompatibilities.  UNIX `troff' interprets
  1296.  
  1297.  
  1298.      .dsabcd
  1299.  
  1300. as defining a string `ab' with contents `cd'.  Normally, GNU `troff'
  1301. interprets this as a call of a macro named `dsabcd'.  Also UNIX `troff'
  1302. interprets `\*[' or `\n[' as references to a string or number register
  1303. called `['.  In GNU `troff', however, this is normally interpreted as
  1304. the start of a long name.  In compatibility mode GNU `troff' interprets
  1305. long names in the traditional way (which means that they are not
  1306. recognized as names).  Compatibility mode can be turned on with the
  1307. `-C' command line option, and turned on or off with the `cp' request.
  1308. The number register `.C' is 1 if compatibility mode is on, 0 otherwise.
  1309.  
  1310.    GNU `troff' does not allow the use of the escape sequences `\|',
  1311. `\^', `\&', `\{', `\}', `\<SP>', `\'', `\`', `\-', `\_', `\!', `\%',
  1312. and `\c' in names of strings, macros, diversions, number registers,
  1313. fonts or environments; UNIX `troff' does.  The `\A' escape sequence
  1314. (*note Identifiers::) may be helpful in avoiding use of these escape
  1315. sequences in names.
  1316.  
  1317.    Fractional point sizes cause one noteworthy incompatibility.  In
  1318. UNIX `troff' the `ps' request ignores scale indicators and thus
  1319.  
  1320.  
  1321.      .ps 10u
  1322.  
  1323. sets the point size to 10 points, whereas in GNU `troff' it sets the
  1324. point size to 10 scaled points.  *Note Fractional Type Sizes::, for
  1325. more information.
  1326.  
  1327.    In GNU `troff' there is a fundamental difference between
  1328. unformatted, input characters, and formatted, output characters.
  1329. Everything that affects how an output character is output is stored
  1330. with the character; once an output character has been constructed it is
  1331. unaffected by any subsequent requests that are executed, including
  1332. `bd', `cs', `tkf', `tr', or `fp' requests.  Normally output characters
  1333. are constructed from input characters at the moment immediately before
  1334. the character is added to the current output line.  Macros, diversions
  1335. and strings are all, in fact, the same type of object; they contain
  1336. lists of input characters and output characters in any combination.  An
  1337. output character does not behave like an input character for the
  1338. purposes of macro processing; it does not inherit any of the special
  1339. properties that the input character from which it was constructed might
  1340. have had.  For example,
  1341.  
  1342.  
  1343.      .di x
  1344.      \\\\
  1345.      .br
  1346.      .di
  1347.      .x
  1348.  
  1349. prints `\\' in GNU `troff'; each pair of input backslashes is turned
  1350. into one output backslash and the resulting output backslashes are not
  1351. interpreted as escape characters when they are reread.  UNIX `troff'
  1352. would interpret them as escape characters when they were reread and
  1353. would end up printing one `\'.  The correct way to obtain a printable
  1354. backslash is to use the `\e' escape sequence: This always prints a
  1355. single instance of the current escape character, regardless of whether
  1356. or not it is used in a diversion; it also works in both GNU `troff' and
  1357. UNIX `troff'.  To store, for some reason, an escape sequence in a
  1358. diversion that will be interpreted when the diversion is reread, either
  1359. use the traditional `\!' transparent output facility, or, if this is
  1360. unsuitable, the new `\?' escape sequence.
  1361.  
  1362.    *Note Diversions::, for more information.
  1363.  
  1364. 
  1365. File: groff,  Node: Summary,  Prev: Implementation Differences,  Up: gtroff Reference
  1366.  
  1367. Summary
  1368. =======
  1369.  
  1370. 
  1371. File: groff,  Node: Preprocessors,  Next: Output Devices,  Prev: gtroff Reference,  Up: Top
  1372.  
  1373. Preprocessors
  1374. *************
  1375.  
  1376.    This chapter describes all preprocessors that come with `groff' or
  1377. which are freely available.
  1378.  
  1379. * Menu:
  1380.  
  1381. * geqn::
  1382. * gtbl::
  1383. * gpic::
  1384. * ggrn::
  1385. * grap::
  1386. * grefer::
  1387. * gsoelim::
  1388.  
  1389. 
  1390. File: groff,  Node: geqn,  Next: gtbl,  Prev: Preprocessors,  Up: Preprocessors
  1391.  
  1392. `geqn'
  1393. ======
  1394.  
  1395. * Menu:
  1396.  
  1397. * Invoking geqn::
  1398.  
  1399. 
  1400. File: groff,  Node: Invoking geqn,  Prev: geqn,  Up: geqn
  1401.  
  1402. Invoking `geqn'
  1403. ---------------
  1404.  
  1405. 
  1406. File: groff,  Node: gtbl,  Next: gpic,  Prev: geqn,  Up: Preprocessors
  1407.  
  1408. `gtbl'
  1409. ======
  1410.  
  1411. * Menu:
  1412.  
  1413. * Invoking gtbl::
  1414.  
  1415. 
  1416. File: groff,  Node: Invoking gtbl,  Prev: gtbl,  Up: gtbl
  1417.  
  1418. Invoking `gtbl'
  1419. ---------------
  1420.  
  1421. 
  1422. File: groff,  Node: gpic,  Next: ggrn,  Prev: gtbl,  Up: Preprocessors
  1423.  
  1424. `gpic'
  1425. ======
  1426.  
  1427. * Menu:
  1428.  
  1429. * Invoking gpic::
  1430.  
  1431. 
  1432. File: groff,  Node: Invoking gpic,  Prev: gpic,  Up: gpic
  1433.  
  1434. Invoking `gpic'
  1435. ---------------
  1436.  
  1437. 
  1438. File: groff,  Node: ggrn,  Next: grap,  Prev: gpic,  Up: Preprocessors
  1439.  
  1440. `ggrn'
  1441. ======
  1442.  
  1443. * Menu:
  1444.  
  1445. * Invoking ggrn::
  1446.  
  1447. 
  1448. File: groff,  Node: Invoking ggrn,  Prev: ggrn,  Up: ggrn
  1449.  
  1450. Invoking `ggrn'
  1451. ---------------
  1452.  
  1453. 
  1454. File: groff,  Node: grap,  Next: grefer,  Prev: ggrn,  Up: Preprocessors
  1455.  
  1456. `grap'
  1457. ======
  1458.  
  1459.    A free implementation of `grap', written by Ted Faber, is available
  1460. as an extra package from the following address:
  1461.  
  1462.      <http://www.lunabase.org/~faber/Vault/software/grap/>
  1463.  
  1464. 
  1465. File: groff,  Node: grefer,  Next: gsoelim,  Prev: grap,  Up: Preprocessors
  1466.  
  1467. `grefer'
  1468. ========
  1469.  
  1470. * Menu:
  1471.  
  1472. * Invoking grefer::
  1473.  
  1474. 
  1475. File: groff,  Node: Invoking grefer,  Prev: grefer,  Up: grefer
  1476.  
  1477. Invoking `grefer'
  1478. -----------------
  1479.  
  1480. 
  1481. File: groff,  Node: gsoelim,  Prev: grefer,  Up: Preprocessors
  1482.  
  1483. `gsoelim'
  1484. =========
  1485.  
  1486. * Menu:
  1487.  
  1488. * Invoking gsoelim::
  1489.  
  1490. 
  1491. File: groff,  Node: Invoking gsoelim,  Prev: gsoelim,  Up: gsoelim
  1492.  
  1493. Invoking `gsoelim'
  1494. ------------------
  1495.  
  1496. 
  1497. File: groff,  Node: Output Devices,  Next: File formats,  Prev: Preprocessors,  Up: Top
  1498.  
  1499. Output Devices
  1500. **************
  1501.  
  1502. * Menu:
  1503.  
  1504. * Special Characters::
  1505. * grotty::
  1506. * grops::
  1507. * grodvi::
  1508. * grolj4::
  1509. * grolbp::
  1510. * grohtml::
  1511. * gxditview::
  1512.  
  1513. 
  1514. File: groff,  Node: Special Characters,  Next: grotty,  Prev: Output Devices,  Up: Output Devices
  1515.  
  1516. Special Characters
  1517. ==================
  1518.  
  1519.    *Note Font Files::.
  1520.  
  1521. 
  1522. File: groff,  Node: grotty,  Next: grops,  Prev: Special Characters,  Up: Output Devices
  1523.  
  1524. `grotty'
  1525. ========
  1526.  
  1527. * Menu:
  1528.  
  1529. * Invoking grotty::
  1530.  
  1531. 
  1532. File: groff,  Node: Invoking grotty,  Prev: grotty,  Up: grotty
  1533.  
  1534. Invoking `grotty'
  1535. -----------------
  1536.  
  1537. 
  1538. File: groff,  Node: grops,  Next: grodvi,  Prev: grotty,  Up: Output Devices
  1539.  
  1540. `grops'
  1541. =======
  1542.  
  1543. * Menu:
  1544.  
  1545. * Invoking grops::
  1546. * Embedding PostScript::
  1547.  
  1548. 
  1549. File: groff,  Node: Invoking grops,  Next: Embedding PostScript,  Prev: grops,  Up: grops
  1550.  
  1551. Invoking `grops'
  1552. ----------------
  1553.  
  1554. 
  1555. File: groff,  Node: Embedding PostScript,  Prev: Invoking grops,  Up: grops
  1556.  
  1557. Embedding POSTSCRIPT
  1558. --------------------
  1559.  
  1560. 
  1561. File: groff,  Node: grodvi,  Next: grolj4,  Prev: grops,  Up: Output Devices
  1562.  
  1563. `grodvi'
  1564. ========
  1565.  
  1566. * Menu:
  1567.  
  1568. * Invoking grodvi::
  1569.  
  1570. 
  1571. File: groff,  Node: Invoking grodvi,  Prev: grodvi,  Up: grodvi
  1572.  
  1573. Invoking `grodvi'
  1574. -----------------
  1575.  
  1576. 
  1577. File: groff,  Node: grolj4,  Next: grolbp,  Prev: grodvi,  Up: Output Devices
  1578.  
  1579. `grolj4'
  1580. ========
  1581.  
  1582. * Menu:
  1583.  
  1584. * Invoking grolj4::
  1585.  
  1586. 
  1587. File: groff,  Node: Invoking grolj4,  Prev: grolj4,  Up: grolj4
  1588.  
  1589. Invoking `grolj4'
  1590. -----------------
  1591.  
  1592. 
  1593. File: groff,  Node: grolbp,  Next: grohtml,  Prev: grolj4,  Up: Output Devices
  1594.  
  1595. `grolbp'
  1596. ========
  1597.  
  1598. * Menu:
  1599.  
  1600. * Invoking grolbp::
  1601.  
  1602. 
  1603. File: groff,  Node: Invoking grolbp,  Prev: grolbp,  Up: grolbp
  1604.  
  1605. Invoking `grolbp'
  1606. -----------------
  1607.  
  1608. 
  1609. File: groff,  Node: grohtml,  Next: gxditview,  Prev: grolbp,  Up: Output Devices
  1610.  
  1611. `grohtml'
  1612. =========
  1613.  
  1614. * Menu:
  1615.  
  1616. * Invoking grohtml::
  1617.  
  1618. 
  1619. File: groff,  Node: Invoking grohtml,  Prev: grohtml,  Up: grohtml
  1620.  
  1621. Invoking `grohtml'
  1622. ------------------
  1623.  
  1624. 
  1625. File: groff,  Node: gxditview,  Prev: grohtml,  Up: Output Devices
  1626.  
  1627. `gxditview'
  1628. ===========
  1629.  
  1630. * Menu:
  1631.  
  1632. * Invoking gxditview::
  1633.  
  1634. 
  1635. File: groff,  Node: Invoking gxditview,  Prev: gxditview,  Up: gxditview
  1636.  
  1637. Invoking `gxditview'
  1638. --------------------
  1639.  
  1640. 
  1641. File: groff,  Node: File formats,  Next: Installation,  Prev: Output Devices,  Up: Top
  1642.  
  1643. File formats
  1644. ************
  1645.  
  1646. * Menu:
  1647.  
  1648. * gtroff Output::
  1649. * Font Files::
  1650.  
  1651. 
  1652. File: groff,  Node: gtroff Output,  Next: Font Files,  Prev: File formats,  Up: File formats
  1653.  
  1654. `gtroff' Output
  1655. ===============
  1656.  
  1657.    This section describes the format output of GNU `troff'.  The output
  1658. format used by GNU `troff' is very similar - but not identical - to
  1659. that used by UNIX device-independent `troff' (`ditroff').
  1660.  
  1661. * Menu:
  1662.  
  1663. * Output Format::
  1664. * Device Control::
  1665. * Drawing Functions::
  1666. * Line Continuation::
  1667.  
  1668.